Overview

This PR represents a major refactoring of ActiveAgent's provider integration layer, replacing our custom type definitions with native types from the official provider gems (anthropic, openai, and ollama via OpenAI compatibility). This change significantly reduces our maintenance burden while improving reliability and future compatibility.

Key Changes

Architecture Shift

• Before: Maintained custom Ruby class hierarchies mirroring each provider's API structures
• After: Leverage native gem types with thin transformation layers

Significant Code Reduction

• Added: ~3,150 lines (transformation utilities + request handling improvements)
• Deleted: ~6,660 lines (custom type definitions across all providers)
• Net reduction: ~3,500 lines of maintainable code
• Files changed: 174 files (excluding reference documentation)

Note: This PR also removes the 65k-line schema.yml reference file that was no longer needed, but the real impact is the ~3.5k reduction in actual code we need to maintain.

Provider-by-Provider Refactoring

1. Anthropic Provider (a9ef325)

• Removed custom message, content, tool_choice, thinking_config, and metadata classes (~1,500 lines)
• Added Anthropic::Transforms module (+353 lines) for bidirectional parameter transformation
• Simplified request handling to use Anthropic gem's native Anthropic::Messages::MessageCreateParams

2. OpenAI Responses Provider (0b1798d)

• Eliminated extensive custom input types (~2,300 lines across 60+ files)
• Created OpenAI::Responses::Transforms (+228 lines) for response format normalization
• Now uses OpenAI::ResponseCreateParameters directly

3. OpenAI Chat Provider (4671886)

• Removed custom message content types (~1,400 lines: images, audio, text, tools, etc.)
• Added OpenAI::Chat::Transforms (+364 lines) for message and response_format handling
• Leverages OpenAI::ChatCompletionParameters from the gem

4. OpenAI Embeddings (94dbd07)

• Simplified embedding request handling (removed ~50 lines of custom types)
• Added OpenAI::Embedding::Transforms (+88 lines) for parameter normalization
• Uses OpenAI::EmbeddingParameters natively

5. OpenRouter Provider (ef7d870)

• Refactored to use OpenAI gem types (OpenRouter is OpenAI-compatible)
• Added OpenRouter::Transforms (+134 lines) for provider-specific extensions
• Maintains OpenRouter-specific features (provider preferences, plugins) while reducing ~230 lines

6. Ollama Provider (7088a6f)

• Migrated both chat and embedding to use OpenAI gem types (removed ~350 lines)
• Added Ollama::Chat::Transforms (+135 lines) and Ollama::Embedding::Transforms (+160 lines)
• Handles Ollama-specific options while maintaining OpenAI compatibility

7. Request Normalization (02404dc)

• Unified parameter normalization across all providers
• Improved cleanup processes for request/response handling
• Enhanced error handling consistency

Benefits

1. Reduced Maintenance Burden

• No need to update custom types when providers release API changes
• Provider gems handle schema validation and type safety
• Automatic compatibility with new features from provider gems

2. Improved Reliability

• Official gems are tested against real provider APIs
• Less surface area for bugs in our codebase
• Type safety improvements from using well-tested gem types

3. Better Performance

• Removed unnecessary object instantiation overhead
• More efficient parameter transformation
• Cleaner request/response lifecycle

4. Enhanced Developer Experience

• Simpler codebase to understand and debug (3.5k fewer lines to maintain)
• Direct access to provider gem documentation
• Easier to contribute provider-specific enhancements

Transform Modules

Each provider now has a dedicated Transforms module that handles:

• Parameter normalization: Converting ActiveAgent's convenient shorthand formats to native gem formats
• Gem-to-hash conversion: Serializing gem objects for ActiveAgent's internal use
• Provider-specific extensions: Handling unique features per provider

Example from Anthropic::Transforms:

# Converts gem model object to hash via JSON round-trip
def gem_to_hash(gem_object)
  JSON.parse(gem_object.to_json, symbolize_names: true)
end

# Normalizes parameters and merges consecutive same-role messages
def normalize_params(params)
  params = params.dup
  params[:messages] = normalize_messages(params[:messages]) if params[:messages]
  params[:system] = normalize_system(params[:system]) if params[:system]
  params
end

Breaking Changes

⚠️ None - This is an internal refactoring. The public API surface remains unchanged. All existing agent code should continue to work without modifications.

Testing

• All existing tests pass
• Provider integration tests verify compatibility with native gems
• VCR cassettes updated to reflect new request/response formats

Files Changed

Major additions:

• lib/active_agent/providers/anthropic/transforms.rb (+353 lines)
• lib/active_agent/providers/open_ai/chat/transforms.rb (+364 lines)
• lib/active_agent/providers/open_ai/responses/transforms.rb (+228 lines)
• lib/active_agent/providers/open_ai/embedding/transforms.rb (+88 lines)
• lib/active_agent/providers/ollama/chat/transforms.rb (+135 lines)
• lib/active_agent/providers/ollama/embedding/transforms.rb (+160 lines)
• lib/active_agent/providers/open_router/transforms.rb (+134 lines)

Major deletions:

• All custom request type classes across providers (~6,660 lines)
• Redundant message/content/tool type definitions
• Reference schema.yml file (65,937 lines - was documentation only)

Summary

This refactoring eliminates ~3,500 lines of custom provider types that we had to maintain and keep in sync with upstream APIs. By leveraging the official provider gems' native types, we've made ActiveAgent more maintainable, reliable, and future-proof while preserving full backward compatibility.

This refactoring positions ActiveAgent to scale more effectively while reducing technical debt and improving long-term maintainability.